Pagination Component
Note: Spartacus 4.x is no longer maintained. Please upgrade to the latest version.
Note: Spartacus 4.x was tested with SAP Commerce Cloud versions 1905 to 2205. Spartacus 4.x has not been verified to work with (and is not guaranteed to work with) SAP Commerce Cloud 2211 or later releases.
Note: Improvements to this feature are introduced with version 2.0 of the Spartacus libraries.
The pagination component is a low-level component that is used to navigate through page results. It is used in various other components, including the Product List, Order History, and Store Finder components.
Each customer has different pagination requirements, especially with regards to the precise navigation options that you use. The pagination component is very flexible and can be adjusted to meet your needs, either through configuration, or by using custom styles.
For the Product List in particular, the pagination component can be replaced by the infinite scroll feature. For more information, see Infinite Scroll.
Table of Contents
Pagination Structure
The pagination component is comprised of anchor links. The anchor links can be used as href
links, or as action links (such as onclick
events). The type of anchor links that are rendered depends on the number of total pages, as well as the configuration that is applied. If you apply the full structure, the following pagination navigation is available:
« ‹ 1 ... 5 (6) 7 ... 11 › »
The example above contains the follow navigation links:
- start:
«
- previous:
‹
- first:
1
- gap:
...
- page range, with the current page centered whenever possible:
5 (6) 7
- gap:
...
- last:
11
- next:
›
- end:
»
Pagination Configuration
You can configure various options for the pagination component, which allows you to reuse the component across the application.
Despite this large number of options, the default configuration in Spartacus uses only a limited feature set: a start link, the page range, and an end link. This appears as follows:
« 1 2 3 »
The following list provides a description of each option that is available in the pagination component:
addStart
adds a link to skip to the start of the pages. The default is set to true.addPrevious
adds a link to the previous page. The default is set to false.addFirst
adds a link to the first page. The default is set to false.addDots
adds a gap with dots to indicate hidden pages. The default is set to false.rangeCount
sets the range of pages that are directly accessible in the pagination. The default is set to3
.addLast
adds a link to the last page. The default is set to false.addNext
adds a link to the previous page. The default is set to false.addEnd
adds a link to skip to the end of the pages. The default is set to true.
In addition, the position of the navigation links can be specified, which allows you to separate them from the pages. Although you can achieve this entirely with CSS rules, when considering accessibility, a preferred approach is to provide the actual, required DOM.
All of the labels that are used in the navigation can be configured as well.
Pagination Styling
The pagination component selector is cx-pagination
, and is comprised of anchor links.
Selectors
Each navigation option in the pagination component is rendered as an anchor link with a specific CSS selector (class), as follows:
- a.start
- a.previous
- a.first
- a.gap
- a.page
- a.page.current
- a.last
- a.next
- a.end
Hiding Navigation in a Specific Instance of the Navigation Component
Although the pagination component is very flexible, the configuration options that have been described so far are applied globally to all instances of the pagination component. If you need to hide navigation options for a specific instance, you can apply CSS rules to hide the navigation options for that instance.
The following example shows a global configuration for the pagination, with a first page, a last page, and a gap with dots in between:
ConfigModule.withConfig({
pagination: {
addFirst: true,
addLast: true,
addDots: true
}
});
You can then use CSS rules to suppress these options for a specific instance, such as the store finder search results. The following is an example:
cx-store-finder-search-result {
cx-pagination {
a.gap,
a.first,
a.last {
display: none;
}
}
}
Component Usage
The pagination component can be used by any UI that needs to navigate a list of things. The pagination component emits an onclick event to the viewPageEvent
output, which you can use to take further action.
The following code snippet shows a simple example of pagination with action links.
<cx-pagination
[pagination]="pagination"
(viewPageEvent)="doPaginationYourself($event)"
></cx-pagination>
Alternatively, you can pass in a pageRoute
and optional queryParam
to generate specific anchor links. The queryParam
is often used to generate the pagination parameter. When defaultPage
is passed in, the queryParam
is removed when the current page is equal to the default page. This cleans up the URL nicely.
The following code snippet shows a simple example of pagination with anchor links.
<cx-pagination
[pagination]="model"
queryParam="currentPage"
[defaultPage]="0"
></cx-pagination>